<html>
<head><meta charset="utf-8"><title>macros 2.0 · rustdoc · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/index.html">rustdoc</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html">macros 2.0</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="246390237"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246390237" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246390237">(Jul 18 2021 at 17:50)</a>:</h4>
<p><span class="user-mention" data-user-id="232545">@Joshua Nelson</span> I seem to recall you saying that macros 2.0 support in rustdoc is less than ideal, and I'm having difficulty with it right now and I'm curious if my problem is already understood and/or something I could easily fix. Specifically when you define a macro in a submodule, and then you export that submodule via <code>pub use</code>, the macro definition does not show up in the generated docs. Non-macro items show up as expected, and the behavior doesn't manifest if the submodule is just directly exported via <code>pub mod</code> rather than via <code>pub use</code>.</p>



<a name="246390253"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246390253" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246390253">(Jul 18 2021 at 17:51)</a>:</h4>
<p>Example:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#![feature(decl_macro)]</span><span class="w"></span>

<span class="k">mod</span> <span class="nn">outer</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="sd">/// I am module documentation</span>
<span class="w">    </span><span class="k">pub</span><span class="w"> </span><span class="k">mod</span> <span class="nn">inner</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="sd">/// I am macro documentation</span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="kr">macro</span><span class="w"> </span><span class="n">some_macro</span><span class="p">()</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>

<span class="w">        </span><span class="sd">/// I am struct documentation</span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">SomeStruct</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// GOOD: this shows up properly in the top-level crate docs</span>
<span class="k">pub</span><span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="n">outer</span>::<span class="n">inner</span>::<span class="n">SomeStruct</span><span class="p">;</span><span class="w"></span>

<span class="c1">// GOOD: this shows up properly in the top-level crate docs</span>
<span class="k">pub</span><span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="n">outer</span>::<span class="n">inner</span>::<span class="n">some_macro</span><span class="p">;</span><span class="w"></span>

<span class="c1">// BAD: the `inner` module-level documentation shows the struct, but not the macro.</span>
<span class="c1">// If `outer` did not exist and `inner` were instead directly exported,</span>
<span class="c1">// then both items show up as expected.</span>
<span class="k">pub</span><span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="n">outer</span>::<span class="n">inner</span><span class="p">;</span><span class="w"></span>
</code></pre></div>



<a name="246390398"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246390398" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246390398">(Jul 18 2021 at 17:54)</a>:</h4>
<p>it's not a problem in name resolution itself; if you attempt to use the macro exported in such a way then it resolves successfully. it's just something with the docs</p>



<a name="246390475"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246390475" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246390475">(Jul 18 2021 at 17:56)</a>:</h4>
<p>what's worse is that not only is the macro not listed in the module-level docs, but if you remove that top-level export then the macro just plain doesn't exist at all in the docs, you can't search for it and its page doesn't get generated</p>



<a name="246390827"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246390827" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246390827">(Jul 18 2021 at 18:04)</a>:</h4>
<p>Looks like the same problem arises if you attempt to <code>pub use</code> with glob imports in any capacity, perhaps it's the same cause</p>



<a name="246391145"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246391145" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246391145">(Jul 18 2021 at 18:11)</a>:</h4>
<p>I personally am not willing to accept any fixes for the hack for macros 2.0, other than the proper fix of getting rid of it. If this affects things other than macros then it's worth opening an issue; I vaguely remember that rustdoc handles glob reexports wrong somehow, there's a closed PR a while back.</p>



<a name="246391261"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246391261" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246391261">(Jul 18 2021 at 18:14)</a>:</h4>
<p>is there a tracking issue for "doing macros 2.0 support properly"?</p>



<a name="246391282"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246391282" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246391282">(Jul 18 2021 at 18:15)</a>:</h4>
<p>I'm not sure. There are lots of comments by Petrochenkov, but they're scattered around various issues. Search for "exported_macros" (it needs to be removed completely for this to work properly)</p>



<a name="246391335"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246391335" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246391335">(Jul 18 2021 at 18:16)</a>:</h4>
<p>Basically what's going on is that rustdoc is trying to reconstruct the privacy information after the fact. Rustc_resolve should just do that itself instead of giving rustdoc wrong information.</p>



<a name="246391405"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246391405" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246391405">(Jul 18 2021 at 18:18)</a>:</h4>
<p>There's a writeup on the PR originally adding the hack I think</p>



<a name="246392438"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%202.0/near/246392438" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> bstrie <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.202.2E0.html#246392438">(Jul 18 2021 at 18:44)</a>:</h4>
<p>I've filed an issue at <a href="https://github.com/rust-lang/rust/issues/87257">https://github.com/rust-lang/rust/issues/87257</a></p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>